home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #5 / Amiga Plus CD - 2000 - No. 5.iso / Tools / Libs / MCC_Lamp / Developer / Autodocs / MCC_Lamp.doc < prev   
Encoding:
Text File  |  1997-03-15  |  9.1 KB  |  288 lines
  1. TABLE OF CONTENTS
  2.  
  3. Lamp.mcc/Lamp.mcc
  4. Lamp.mcc/MUIA_Lamp_Blue
  5. Lamp.mcc/MUIA_Lamp_Color
  6. Lamp.mcc/MUIA_Lamp_ColorType
  7. Lamp.mcc/MUIA_Lamp_Green
  8. Lamp.mcc/MUIA_Lamp_PenSpec
  9. Lamp.mcc/MUIA_Lamp_Red
  10. Lamp.mcc/MUIA_Lamp_Type
  11. Lamp.mcc/MUIM_Lamp_SetRGB
  12. Lamp.mcc/Lamp.mcc                                           Lamp.mcc/Lamp.mcc
  13.  
  14. Lamp.mcc offers a little lamp which can be used for various purposes. It
  15. enhances the programmer's abilities to give more informative feedback to the
  16. user and thus just adds another level of communication in your programs!
  17.  
  18. You can set the color and the type of the lamp at any time.
  19.  
  20. Lamp.mcc has several special colors which can be configured using a MCP by
  21. the user.
  22.  
  23. See the supplied demonstration program for more details.
  24.  
  25. The demonstration program compiles fine under MaxonC++ 4.0, SAS/C 6.57 and
  26. StormC 1.1.
  27.  
  28.  
  29. Some notes about colors:
  30.  
  31. The color of the lamp can be of one of three different types:
  32.  
  33. - a user defined special color, such as "sending data" indicators
  34. - a "normal" color consisting of red/green/blue color values
  35. - a PenSpec definition
  36.  
  37. If you want to get() the color values from a lamp, it is always required to
  38. determine which color type the desired lamp has. To determine the color type
  39. of a lamp, you must use MUIA_Lamp_ColorType.
  40.  
  41. Example: If the lamp has a color type of "user defined color", you cannot
  42. get() the red/green/blue values, since this is a user definition and should
  43. not be known to the programmer.
  44.  
  45. Here is some example code of how you could do it:
  46.  
  47.   ULONG type;
  48.  
  49.   get(lamp, MUIA_Lamp_ColorType, &type);
  50.   switch (type)
  51.   {
  52.     case MUIV_Lamp_ColorType_UserDefined:
  53.       /*
  54.       ** user defined color values specific code
  55.       ** (you could get() MUIA_Lamp_Color here)
  56.       */
  57.     case MUIV_Lamp_ColorType_Color:
  58.       /*
  59.       ** normal color specific code
  60.       ** (you could get() MUIA_Lamp_Red, MUIA_Lamp_Green, MUIA_Lamp_Blue and
  61.       ** MUIA_Lamp_Color here)
  62.       */
  63.     case MUIV_Lamp_ColorType_PenSpec:
  64.       /*
  65.       ** PenSpec definition specific code
  66.       ** (you could get() MUIA_Lamp_PenSpec here)
  67.       */
  68.   }
  69. Lamp.mcc/MUIA_Lamp_Blue                               Lamp.mcc/MUIA_Lamp_Blue
  70.  
  71.    NAME
  72.        MUIA_Lamp_Blue -- [ISG], ULONG
  73.  
  74.    FUNCTION
  75.        Set or get a lamp's blue color value.
  76.  
  77.        Values range from 0 (no blue) to 0xffffffff (full blue).
  78.  
  79.    NOTES
  80.        You may only get() MUIA_Lamp_Blue if MUIA_Lamp_ColorType is set
  81.        to MUIV_Lamp_ColorType_Color! If not, the return value will be
  82.        undefined.
  83.  
  84.        Setting this attribute will always set MUIA_Lamp_ColorType to
  85.        MUIV_Lamp_ColorType_Color.
  86.  
  87.    SEE ALSO
  88.        MUIA_Lamp_Red, MUIA_Lamp_Green, MUIA_Lamp_Color, MUIA_Lamp_PenSpec,
  89.        MUIA_Lamp_ColorType,
  90.        MUIM_Lamp_SetRGB
  91. Lamp.mcc/MUIA_Lamp_Color                             Lamp.mcc/MUIA_Lamp_Color
  92.  
  93.    NAME
  94.        MUIA_Lamp_Color -- [ISG], ULONG *
  95.  
  96.    FUNCTION
  97.        Set or get the red/green/blue color values all at once. You pass
  98.        in or receive a pointer to an array of three ULONG containing the
  99.        32-bit red, green and blue values.
  100.  
  101.        You can also set one of the special input values to get a special
  102.        lamp color.
  103.  
  104.        The default value is MUIV_Lamp_Color_Off.
  105.  
  106.    SPECIAL INPUTS
  107.        MUIV_Lamp_Color_Off           - lamp is switched off
  108.        MUIV_Lamp_Color_Ok            - no problems, success
  109.        MUIV_Lamp_Color_Warning       - a warning only
  110.        MUIV_Lamp_Color_Error         - something wrong
  111.        MUIV_Lamp_Color_FatalError    - complete or severe failure
  112.        MUIV_Lamp_Color_Processing    - any program work in progress
  113.        MUIV_Lamp_Color_LookingUp     - looking up a server
  114.        MUIV_Lamp_Color_Connecting    - connecting to a server
  115.        MUIV_Lamp_Color_SendingData   - sending any serial line data
  116.        MUIV_Lamp_Color_ReceivingData - receiving any serial line data
  117.        MUIV_Lamp_Color_LoadingData   - loading any data into memory
  118.        MUIV_Lamp_Color_SavingData    - saving any data onto (hard)disk
  119.  
  120.    NOTES
  121.        The input is buffered, you may destroy your private array after
  122.        set()ting the color.
  123.  
  124.        You may not modify the returned array, it is read-only!
  125.  
  126.        Be prepared to get one of the special input values.
  127.  
  128.        You may only get() MUIA_Lamp_Color if MUIA_Lamp_ColorType is set
  129.        to MUIV_Lamp_ColorType_Color or MUIV_Lamp_ColorType_UserDefined!
  130.        If not, the return value will be undefined.
  131.  
  132.        Setting this attribute to a pointer to an array of three ULONG will
  133.        set MUIA_Lamp_ColorType to MUIV_Lamp_ColorType_Color.
  134.  
  135.        Setting this attribute to one of the special input values will set
  136.        MUIA_Lamp_ColorType to MUIV_Lamp_ColorType_UserDefined.
  137.  
  138.    EXAMPLE
  139.        /* set color to yellow */
  140.        ULONG yellow[3] =
  141.        {
  142.          0xffffffff,
  143.          0xffffffff,
  144.          0
  145.        };
  146.        set(lamp, MUIA_Lamp_Color, &yellow);
  147.  
  148.        /* set color to user defined "warning" color */
  149.        set(lamp, MUIA_Lamp_Color, MUIV_Lamp_Color_Warning);
  150.  
  151.        /* get lamp color */
  152.        ULONG *color;
  153.        get(lamp, MUIA_Lamp_Color, &color);
  154.        printf("red  : 0x%08lx\n"
  155.               "green: 0x%08lx\n"
  156.               "blue : 0x%08lx\n",
  157.               color[0], color[1], color[2]);
  158.  
  159.    SEE ALSO
  160.        MUIA_Lamp_Red, MUIA_Lamp_Green, MUIA_Lamp_Blue, MUIA_Lamp_PenSpec,
  161.        MUIA_Lamp_ColorType,
  162.        MUIM_Lamp_SetRGB
  163. Lamp.mcc/MUIA_Lamp_ColorType                     Lamp.mcc/MUIA_Lamp_ColorType
  164.  
  165.    NAME
  166.        MUIA_Lamp_ColorType -- [..G], ULONG
  167.  
  168.    FUNCTION
  169.        Get the color type of a lamp.
  170.  
  171.    RESULT
  172.        MUIV_Lamp_ColorType_UserDefined - user defined color (preferences)
  173.        MUIV_Lamp_ColorType_Color       - normal color with RGB values
  174.        MUIV_Lamp_ColorType_PenSpec     - a PenSpec definition
  175. Lamp.mcc/MUIA_Lamp_Green                             Lamp.mcc/MUIA_Lamp_Green
  176.  
  177.    NAME
  178.        MUIA_Lamp_Green -- [ISG], ULONG
  179.  
  180.    FUNCTION
  181.        Set or get a lamp's green color value.
  182.  
  183.        Values range from 0 (no green) to 0xffffffff (full green).
  184.  
  185.    NOTES
  186.        You may only get() MUIA_Lamp_Green if MUIA_Lamp_ColorType is set
  187.        to MUIV_Lamp_ColorType_Color! If not, the return value will be
  188.        undefined.
  189.  
  190.        Setting this attribute will always set MUIA_Lamp_ColorType to
  191.        MUIV_Lamp_ColorType_Color.
  192.  
  193.    SEE ALSO
  194.        MUIA_Lamp_Red, MUIA_Lamp_Blue, MUIA_Lamp_Color, MUIA_Lamp_PenSpec,
  195.        MUIA_Lamp_ColorType,
  196.        MUIM_Lamp_SetRGB
  197. Lamp.mcc/MUIA_Lamp_PenSpec                         Lamp.mcc/MUIA_Lamp_PenSpec
  198.  
  199.    NAME
  200.        MUIA_Lamp_PenSpec -- [ISG], struct MUI_PenSpec *
  201.  
  202.    FUNCTION
  203.        Set or get a lamp's PenSpec definition.
  204.  
  205.    NOTES
  206.        The input is buffered, you may destroy your private array after
  207.        set()ting the PenSpec definition.
  208.  
  209.        You may not modify the returned array, it is read-only!
  210.  
  211.        You may only get() MUIA_Lamp_PenSpec if MUIA_Lamp_ColorType is set
  212.        to MUIV_Lamp_ColorType_PenSpec! If not, the return value will be
  213.        undefined.
  214.  
  215.        Setting this attribute will always set MUIA_Lamp_ColorType to
  216.        MUIV_Lamp_ColorType_PenSpec.
  217.  
  218.    SEE ALSO
  219.        MUIA_Lamp_Color, MUIA_Lamp_Red, MUIA_Lamp_Green, MUIA_Lamp_Blue,
  220.        MUIA_Lamp_ColorType,
  221.        MUIM_Lamp_SetRGB
  222. Lamp.mcc/MUIA_Lamp_Red                                 Lamp.mcc/MUIA_Lamp_Red
  223.  
  224.    NAME
  225.        MUIA_Lamp_Red -- [ISG], ULONG
  226.  
  227.    FUNCTION
  228.        Set or get a lamp's red color value.
  229.  
  230.        Values range from 0 (no red) to 0xffffffff (full red).
  231.  
  232.    NOTES
  233.        You may only get() MUIA_Lamp_Red if MUIA_Lamp_ColorType is set
  234.        to MUIV_Lamp_ColorType_Color! If not, the return value will be
  235.        undefined.
  236.  
  237.        Setting this attribute will always set MUIA_Lamp_ColorType to
  238.        MUIV_Lamp_ColorType_Color.
  239.  
  240.    SEE ALSO
  241.        MUIA_Lamp_Green, MUIA_Lamp_Blue, MUIA_Lamp_Color, MUIA_Lamp_PenSpec,
  242.        MUIA_Lamp_ColorType,
  243.        MUIM_Lamp_SetRGB
  244. Lamp.mcc/MUIA_Lamp_Type                               Lamp.mcc/MUIA_Lamp_Type
  245.  
  246.    NAME
  247.        MUIA_Lamp_Type -- [ISG], ULONG
  248.  
  249.    FUNCTION
  250.        Set or get a lamp's type.
  251.  
  252.        The default value is MUIV_Lamp_Type_Medium.
  253.  
  254.    SPECIAL INPUTS
  255.        MUIV_Lamp_Type_Tiny   - 5x5 pixels circular lamp
  256.        MUIV_Lamp_Type_Small  - 6x6 pixels circular lamp
  257.        MUIV_Lamp_Type_Medium - 7x7 pixels circular lamp
  258.        MUIV_Lamp_Type_Big    - 8x8 pixels circular lamp
  259.        MUIV_Lamp_Type_Huge   - 9x9 pixels circular lamp
  260.  
  261.    NOTES
  262.        At the moment, you are only allowed to pass in one of the special
  263.        input values! No other inputs are allowed!
  264.  
  265.        It is guaranteed to get one of the special inputs.
  266. Lamp.mcc/MUIM_Lamp_SetRGB                           Lamp.mcc/MUIM_Lamp_SetRGB
  267.  
  268.    NAME
  269.        MUIM_Lamp_SetRGB
  270.  
  271.    SYNOPSIS
  272.        DoMethod(lamp, MUIM_Lamp_SetRGB, ULONG red, ULONG green, ULONG blue);
  273.  
  274.    FUNCTION
  275.        Set the red/green/blue color values all at once. You pass in three
  276.        ULONG containing the 32-bit red, green and blue values.
  277.  
  278.    NOTES
  279.        Using this method will always set MUIA_Lamp_ColorType to
  280.        MUIV_Lamp_ColorType_Color.
  281.  
  282.    EXAMPLE
  283.        /* set color to yellow */
  284.        DoMethod(lamp, MUIM_Lamp_SetRGB, 0xffffffff, 0xffffffff, 0);
  285.  
  286.    SEE ALSO
  287.        MUIA_Lamp_Red, MUIA_Lamp_Green, MUIA_Lamp_Blue, MUIA_Lamp_Color
  288.